home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 3: CDPD 3
/
Almathera Ten on Ten - Disc 3: CDPD3.iso
/
scope
/
051-075
/
scopedisk61
/
loadiff
/
ifflib.doc
< prev
next >
Wrap
Text File
|
1995-03-19
|
14KB
|
493 lines
THE UNIVERSAL IFF LIBRARY FOR THE AMIGA
BY CHRISTIAN A. WEBER, ZURICH/SWITZERLAND
VERSION 16.1 01-DEC-88
THIS PROGRAM IS IN THE PUBLIC DOMAIN. IT MAY BE FREELY DISTRUBUTED, COPIED
AND USED FOR COMMERCIAL OR NON-COMMERCIAL PURPOSES. IT MAY BE DISTRIBUTED
WITH OR WITHOUT THIS DOCUMENTATION FILE.
TO MAINTAIN COMPATIBILITY, YOU SHOULD NOT MAKE ANY CHANGES ON THE LIBRARY
ITSELF. UPDATES WILL BE RELEASED BY THE AUTHOR.
CHANGES SINCE V15.3
-------------------
Since V15.3 I got lots of suggestions, so I made the following changes.
Note that this version is fully downward-compatible to V15.3.
* There was a bug in the DecodePic() routine which called the guru if the
width of the picture was not a multiple of 16. It's fixed now.
* The GetViewModes() routines now calculates the viewmodes correctly for
all picture sizes, including Super-Overscan (produced by DigiView 3.0).
* When you open an IFF file with the OpenIFF() call, memory is allocated
and the file is read into that memory. Normally, all files are loaded
into whatever memory is available, but '8SVX' files are always loaded to
CHIP memory (the memory which is accessable by the Amiga's custom chips).
This solution is good for playing IFF sounds, but it is not satisfactory
for some other applications. The solution of this problem is quite easy:
I added a new routine called 'NewOpenIFF', which allows you to specify
the type of memory for the file.
So if you want to load an IFF instrument into any RAM, the right command
is: 'f=NewOpenIFF(filename,0L)' or 'f=OpenIFF(filename,MEMF_PUBLIC)'.
You can use any memory attributes you want (PUBLIC,CHIP,FAST...).
* The file 'iff.h' is now split into two files: 'iff.h', which contains the
structure definitions and function declarations, and 'IffGlue.asm',
which contains the C to Assembler interface routines.
* The file 'IFFPragmas.h" is added to support the Lattice C compiler. It
was taken from an usenet article by Lyle E. Levine. Thanks!
* The demo file 'ShowIFF.c' now correctly handles overscan pictures.
THE LIBRARY FUNCTIONS (Overview, Version 16.1)
----------------------------------------------
Name Offset Description
OpenIFF -30 Allocate memory for an IFF-file and load it
CloseIFF -36 Finish access to an IFF-file and deallocate memory
FindChunk -42 Find a specific chunk in an IFF file
GetBMHD -48 Find the BitMapHeader of an ILBM file
GetColorTab -54 Find CMAP chunk, convert it to an Amiga ColorTable
DecodePic -60 Decode the BODY of an ILBM file into a BitMap
SaveBitMap -66 Save the contents of a BitMap as an IFF-file
SaveClip -72 Save a part of a BitMap as an IFF-file
IffError -78 Get detailed error descrpition if a routine fails
GetViewModes -84 Get the Amiga-specific ViewModes-Word
NewOpenIFF -90 Allocate specific memory for an IFF-file and load it
(to be continued)
DETAILED DESCRIPTION OF THE LIBRARY FUNCTIONS
---------------------------------------------
(This documentation was translated from German to English in half an hour,
so please be tolerant!)
IFF/NewOpenIFF IFF/NewOpenIFF
NAME
NewOpenIFF -- allocate memory for an IFF-file and read it
SYNOPSIS
ifffile = NewOpenIFF(filename,memattr)
D0 A0 D0
OFFSET
-90
FUNCTION
This function opens a file on a disk and looks whether it's an IFF
file or not. If it is an IFF file, memory is allocated and the file
is read into memory. The 'memattr' argument is taken to define the
memory type. Normally memattr is set to 0 or MEMF_PUBLIC.
If an error occurs, 0 is returned, and you can call IffError() to
get the error number.
INPUTS
filename - Pointer to a null-terminated string
memattr - Memory requirements as used for Exec's AllocMem(),
such as MEMF_CHIP, MEMF_PUBLIC ...
RESULT
ifffile - 'FileHandle', points to the beginning of the IFF file
("FORM...."), 0 if unsuccessful. Call IffError() to get the
reason of the failure.
SEE ALSO
OpenIFF, CloseIFF, IffError
BUGS
None
IFF/OpenIFF IFF/OpenIFF
NAME
OpenIFF -- allocate memory for an IFF-file and read it
SYNOPSIS
ifffile = OpenIFF(filename)
D0 A0
OFFSET
-90
FUNCTION
This function does the same as the NewOpenIFF() routine above,
except that you cannot specify the type of memory which is
allocated for the file. Normally the type is 0 which means 'any
memory', but if the IFF file type is '8SVX', the file is ALWAYS
loaded into CHIP memory. If you wish to override these defaults,
use NewOpenIFF() instead of OpenIFF().
INPUTS
filename - Pointer to a null-terminated string
RESULT
ifffile - 'FileHandle', points to the beginning of the IFF file
("FORM...."), 0 if unsuccessful. Call IffError() to get the
reason of the failure.
SEE ALSO
NewOpenIFF, CloseIFF, IffError
BUGS
None
IFF/CloseIFF IFF/CloseIFF
NAME
CloseIFF -- finish access to an IFF-file and deallocate memory
SYNOPSIS
CloseIFF(ifffile)
A1
OFFSET
-36
FUNCTION
Returns the memory previously allocated by OpenIFF().
INPUTS
ifffile - IFF file pointer, from OpenIFF()
RESULT
none
SEE ALSO
OpenIFF
BUGS
If A1 contains garbage, an 81000005 Guru will visit you...
IFF/FindChunk IFF/FindChunk
NAME
FindChunk -- find an IFF-chunk
SYNOPSIS
chunk = FindChunk(ifffile,chunkname)
D0 A1 D0
OFFSET
-42
FUNCTION
Find a specific chunk in an IFF file
INPUTS
ifffile - IFF file pointer, returned by OpenIFF()
chunkname - 4 characters packed ASCII ('BODY', 'VHDR' ...)
RESULT
Pointer to the beginning of the chunk (that means to the chunk
name itself, followed by the chunk size), zero if chunk not found
SEE ALSO
GetBMHD, GetColorTab
BUGS
none
IFF/GetBMHD IFF/GetBMHD
NAME
GetBMHD -- find a BitMapHeader of an IFF-file
SYNOPSIS
header = GetBMHD(ifffile)
D0 A1
OFFSET
-48
FUNCTION
Returns a pointer to a 'BitMapHeader' structure as defined in
iff.h and iff.i
INPUTS
ifffile - IFF file pointer, returned by OpenIFF()
RESULT
Pointer to the BitMapHeader, or 0 if no BMHD chunk found
SEE ALSO
FindChunk, GetColorTab
BUGS
none
IFF/GetColorTab IFF/GetColorTab
NAME
GetColorTab -- find a CMAP chunk and convert it to a ColorTable
SYNOPSIS
count = GetColorTab(ifffile,colortable)
D0 A1 A0
OFFSET
-54
FUNCTION
Searches the CMAP chunk of an IFF file and converts it, if it's
there, to an Amiga color table structure. This colortable can
directly be used as a parameter for the LoadRGB4() function.
INPUTS
ifffile - IFF file pointer, returned by OpenIFF()
colortable - Pointer to a block of memory which must be large
enough to hold the colortable (2 bytes per color)
RESULT
Number of colors actually found, or zero if the file has no
CMAP chunk
SEE ALSO
FindChunk, GetBMHD
BUGS
the colortable must be WORD aligned (this isn't really a bug)
IFF/DecodePic IFF/DecodePic
NAME
DecodePic -- decode an IFF-BODY into a BitMap
SYNOPSIS
bitmap = DecodePic(ifffile,bitmap)
D0 A1 A0
OFFSET
-60
FUNCTION
Decodes and decrunches a picture into the BitMap you supplied.
If the picture is larger than your BitMap's planes, it will be
truncated. If your BitMap is larger than the picture, the picture
will be drawn into the top left corner of your BitMap.
If the picture has more planes (colors) than your BitMap, the
operation will fail and 0 will be returned.
INPUTS
ifffile - IFF file pointer, from OpenIFF()
bitmap - Pointer to a properly initialized BitMap structure:
bm_Planes[] must point to valid BitPlanes,
bm_Depth contains the number of planes.
bm_Width and bm_Height must be set according to the
size of your bit planes.
RESULT
Non-zero if OK, 0 if error, Call IffError() to know the reason
of the failure
BUGS
The width of the IFF picture (in pixels) must be a multiple of 8
(I've never seen a picture which didn't obey this rule!)
IFF/SaveBitMap IFF/SaveBitMap
NAME
SaveBitMap -- save the planes of a BitMap as an IFF-file
SYNOPSIS
result = SaveBitMap(filename,bitmap,colortable,flags)
D0 A0 A1 A2 D0
OFFSET
-66
FUNCTION
Save the planes of a BitMap as an IFF-file, optionally with a
colortable. The IFF file will contain the following chunks:
FORM - The IFF header, with the type ILBM
BMHD - The BitMap Header structre
CMAP - The color map, this chunk is omitted if colortable is zero
CAMG - The Amiga ViewModes word, contains the special ViewModes
information (HAM, LACE, HIRES ...)
BODY - The (crunched or uncompressed) picture
INPUTS
filename - Name of the IFF file to create
bitmap - Pointer to the BitMap holding your picture
colortable - Pointer to an Amiga ColorTable structure or zero
(if colortable = 0, no CMAP chunk will be generated).
flags - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
0 = Save the file uncompressed
Bit 7: 1 = This is a HAM (Hold and modify) picture
0 = This is a normal or Extra-Halfbrite picture
RESULT
Non-zero if successful, 0 if error, Call IffError() to know the
reason of the failure
SEE ALSO
SaveClip
IFF/SaveClip IFF/SaveClip
NAME
SaveClip -- save a part of a BitMap as an IFF-file
SYNOPSIS
result = SaveClip(filename,bitmap,coltab,flags,xoff,yoff,width,height)
D0 A0 A1 A2 D0 D1 D2 D3 D4
OFFSET
-72
FUNCTION
Save a part of a BitMap as an IFF file
INPUTS
filename - Name of the IFF file to create
bitmap - Pointer to the BitMap holding your picture
colortable - Pointer to an Amiga ColorTable structure or zero
(if colortable = 0, no CMAP chunk will be generated).
flags - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
0 = Save the file uncompressed
Bit 7: 1 = This is a HAM (Hold and modify) picture
0 = This is a normal or Extra-Halfbrite picture
xoff - X offset of the clip to be saved (bytes from the left)
yoff - Y offset of the clip to be saved (lines from the top)
width - width in bytes of the rectangle
height - height in lines of the rectangle
RESULT
Non-zero if successful, 0 if error, Call IffError() to know the
reason of the failure
SEE ALSO
SaveBitMap
BUGS
The width of the rectangle will be rounded to WORD boundaries,
because DPAINT® wants it!
IFF/IffError IFF/IffError
NAME
IffError -- Get detailed error descrpition
SYNOPSIS
error = IffError()
D0
OFFSET
-78
FUNCTION
If one of the above functions returns zero, you can call IffError()
to know the reason for the failure. An error code is returned,
please refer to the files 'iff.h' or 'iff.i' for the complete
list of errors!
INPUTS
none
RESULT
Error-number generated by the latest function call, or zero if
no error
Cuurently the following numbers are used:
Nr. Symbol Function Description
16 IFF_CANTOPENFILE OpenIFF() File not found
17 IFF_READERROR OpenIFF() Read() returned an error
18 IFF_NOMEM OpenIFF() Not enough memory for the file
19 IFF_NOTIFF OpenIFF() File is not IFF
20 IFF_WRITEERROR SaveBitMap() Cannot write the file
24 IFF_NOILBM DecodePic() IFF file is not an ILBM file
25 IFF_NOBMHD DecodePic() BMHD chunk not found
26 IFF_NOBODY DecodePic() BODY chunk not found
27 IFF_TOOMANYPLANES DecodePic() Picture has more planes than
your BitMap
28 IFF_UNKNOWNCOMPRESSION " Unknown compression type
-1 IFF_BADTASK A task which did not open the IFF library
tried to call IffError(). Since the IFF
library is capable of multi-tasking, the
error-values are stored for each task
separately.
SEE ALSO
BUGS
If you don't close the IFF library at the end of your program
(using CloseLibrary()) the error node will not be freed. The
same task will then not be able to re-open the iff.library!!!
IFF/GetViewModes IFF/GetViewModes
NAME
GetViewModes -- Get Amiga-specific ViewModes-Word
SYNOPSIS
viewmodes = GetViewModes(ifffile)
D0 A1
OFFSET
-84
FUNCTION
Searches the IFF file for a 'CAMG' chunk which holds the view modes
information. If there is no CAMG chunk, the view modes are calcu-
lated using the information in the BitMapHeader structure.
You can set the result of GetViewModes() directly into the
ns_ViewModes field of a NewScreen structure!
INPUTS
ifffile - IFF file pointer, returned from OpenIFF()
RESULT
viewmodes - WORD containing the view modes (HAM, LACE, HIRES ...)
SEE ALSO
BUGS
If the IFF file has no CAMG chunk and 6 bitplanes, the HAM bit
will be set. This is not always correct since the picture could
be in the Extra Halfbrite mode.
PS: The file 'ShowIff.c' shows you how to use the IFF library from C.